This is really interesting, thanks for the PR! I'd like to understand the consequences of this change, as it may change the expectations of the users. For example:

• Should we add any handling to protoc-gen-grpc-gateway of these annotations? What would that mean?

You could certainly add runtime checking for some of the options - REQUIRED, INPUT_ONLY, OUTPUT_ONLY - but I don't believe gateway does anything with the existing required or readonly fields at runtime today? It would have to be an opt in feature because it could potentially be a breaking change for people who documented that behavior but didn't enforce it.

I think it's a reasonable discussion but probably would be a separate issue.

• Adding this file as a dependency of the library runs the risk of annoying all current users who do not have field_behavior.proto vendored (as it wasn't a reqiurement), is this going to break users that don't vendor this file? From a cursory reading I don't think it should since we're just checking if the extensions are set.

Confirmed that there is no compile time dependency on field_behavior.proto.

Also, could we update one of the fields in examples/internal/proto/a_bit_of_everything.proto to add some of these descriptions to show users how they're used?

Will do.

Thanks!

@johanbrandhorst - I think we are all set here.

In relation to the original runtime behavior question, I think there are a couple options for anyone who wants automatic runtime validation against the Swagger spec:

1. Integrate with go-openapi which has an existing validator for OpenAPI schemas: https://godoc.org/github.com/go-openapi/validate#hdr-Validating_a_schema. This would have to be done at the HTTP level since it's validates against JSON which wouldn't be ideal for performance reasons since you'd be parsing the request twice.
2. Code generate validators against the Swagger spec (a la https://github.com/mwitkow/go-proto-validators or https://github.com/envoyproxy/protoc-gen-validate) and use validator middleware to validate at runtime.

I'll update the docs sometime in the next few days.

Codecov Report

Merging #1806 (8d9358d) into master (1f6e7b0) will increase coverage by 0.06%.
The diff coverage is 58.33%.

@@            Coverage Diff             @@
##           master    #1806      +/-   ##
==========================================
+ Coverage   57.32%   57.39%   +0.06%     
==========================================
  Files          34       34              
  Lines        3616     3652      +36     
==========================================
+ Hits         2073     2096      +23     
- Misses       1282     1290       +8     
- Partials      261      266       +5     

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1f6e7b0...8d9358d. Read the comment docs.

@johanbrandhorst I've opened another PR (#1822) to cover the docs piece since the changes were a bit beyond the scope of just field behavior support. Figured we could get this merged and iterate on any docs changes there.

Thanks a ton for your contribution!